/**
 *       Copyright (c) 2012 Lukas Zaruba
 *
 *   This file is part of Robot Playground.
 *
 *   Robot Playground is free software: you can redistribute it and/or modify
 *   it under the terms of the GNU Lesser General Public License as published by
 *   the Free Software Foundation, either version 3 of the License, or
 *   (at your option) any later version.
 *
 *   Robot Playground is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU Lesser General Public License for more details.
 *
 *   You should have received a copy of the GNU Lesser General Public License
 *   along with Robot Playground. If not, see <http://www.gnu.org/licenses/>.
 */
package net.zarubsys.robotplayground.gui.session.providers;

import net.zarubsys.robotplayground.core.session.Session;

import org.eclipse.swt.graphics.Image;

/**
 * ISystemObjectGUIProvider
 * 
 * Implement this interface to make your object available
 * in the GUI. This is the basic interface to be implemented.
 * Check the rest of this package for advanced interfaces.
 *
 * @author Lukas Zaruba, lukas.zaruba@gmail.com
 */
public interface ISystemObjectGUIProvider {
	
	/**
	 * @param id id of the system object
	 * @return an instance of the image
	 * which is displayed in the session editor
	 * 
	 * The image is expected to be 64x64px
	 * 
	 * This provider is responsible for proper disposal and handling of the Image resource
	 */
	Image getImage(String id);
	
	/**
	 * @param id id of the system object
	 * @return the static description of this system object
	 * meaning without any configuration.
	 */
	String getDescription(String id);
	
	/**
	 * @return description of the configured system object
	 */
	String getDescription(Session session, int index);
	
	/**
	 * @return proper class of this device
	 */
	SystemObjectGUIProviderClass getProviderClass();
	
	/**
	 * This method gets invoked once user wants to add the object
	 * represented by this provider into the session.
	 * @param session into which the object should be added
	 * @param id of the object to be added
	 * @return index of the newly added object in its class or -1
	 * if the object was not added
	 */
	int addObjectToSession(Session session, String id);
	
	/**
	 * If this provider is configurable, this method will be called
	 * once the user wants to reconfigure an object represented
	 * by this provider
	 * @param session session in which the action takes place
	 * @param index of the object in its class
	 * @return true if the reconfiguration took the place, false otherwise
	 */
	boolean reconfigure(Session session, int index);
	
	/**
	 * @param id id of the system object
	 * @return true if this object is configurable
	 * false otherwise
	 */
	boolean isConfigurable(String id);
	
	/**
	 * This method is called once the user wants to remove an object
	 * from the session.
	 * @param session session in which the action takes place
	 * @param index of the object in its class
	 * @return true if the object was remove, false otherwise
	 */
	boolean remove(Session session, int index);
	
	/**
	 * This method gets invoked every time there is a reason for
	 * object validation.
	 * @param session session in which the action takes place
	 * @param index of the object in its class
	 * @return null if everything is ok or a message which will be shown
	 * to the user. This message should be descriptive enough to allow the
	 * user to fix the problem.
	 */
	String validate(Session session, int index);

}

